home *** CD-ROM | disk | FTP | other *** search
/ Celestin Apprentice 5 / Apprentice-Release5.iso / Source Code / Add-Ons / MPW / MPW fixit / fixit.txt < prev    next >
Encoding:
Text File  |  1996-03-02  |  8.9 KB  |  268 lines  |  [TEXT/MPS ]
  1. file fixit.txt Copyright (C) 1996 by John Montbriand.  All Rights Reserved.
  2.  
  3. ABOUT FIXIT...
  4.  
  5.     Copyright (C) 1996 by John Montbriand.  All Rights Reserved.
  6.     
  7.     Distribute freely in areas where the laws of copyright apply.
  8.  
  9.     Use at your own risk.
  10.     
  11.     Do not distribute modified copies.
  12.  
  13.     These various fixmath routines and libraries are for free!
  14.  
  15.  
  16. ABOUT THE AUTHOR...
  17.  
  18.     Comments, questions, or suggestions are always welcome.
  19.  
  20.     John Montbriand                tinyjohn@sasknet.sk.ca
  21.     P.O. Box. 1133
  22.     Saskatoon Saskatchewan Canada
  23.     S7K 3N2
  24.  
  25.  
  26. WHY IS IT FOR FREE?
  27.  
  28.     none of your business,
  29.     
  30.     but if you have some business for me,  I'll see what I can do..
  31.  
  32.  
  33. OUTLINE OF TOPICS
  34.  
  35.     FIXIT, WHAT'S IT DO?  WHAT'S IT FOR?
  36.     IMPLEMENTATION NOTES
  37.     MATERIALS
  38.     LEGAL STUFF
  39.     FURTHER REFERENCE
  40.     BE CAREFUL (CAVEATS)
  41.     THE FIXIT TOOL
  42.     FIXIT INPUT FORMAT
  43.     ROUTINES PROVIDED
  44.  
  45.  
  46. FIXIT, WHAT'S IT DO?  WHAT'S IT FOR?
  47.     
  48.     Fixit is an MPW tool that translates easily readable infix
  49.     mathematical expressions into difficult to read and edit fixed
  50.     point math function calling sequences that are suitable for
  51.     use as expressions in C programs.
  52.     
  53.     It also serves as a fixed point expression evaluator.
  54.  
  55.     On most macintoshes, the fixed point math functions are much faster
  56.     than using floating point functions and in some cases they can
  57.     be a very attractive alternative for mathematical processing.
  58.  
  59.  
  60. IMPLEMENTATION NOTES
  61.  
  62.     Some fixed point functions are not defined in the current collection
  63.     Fixed point math routines, hence they have been included here
  64.     in the file fixit.c.  These routines include fixed point functions
  65.     for calculating square root, exponent, square, cosine, sine, and tangent.
  66.     These are described in greater detail below.
  67.  
  68.     The Fixit tool does some constant sub expression (cse) optomization which
  69.     allows you to use it as a fixed point number calculator.  The following
  70.     table illustrates how this happens:
  71.     
  72.     input                  output
  73.     
  74.     cos(3.14 / (22.5 + 7)) 0x0000FE8D
  75.     88.32 + 77/12          0x005EBC97
  76.     sqrt(7.3 - 3)/my_var   FixDiv(0x000212DB, my_var)
  77.     3.14159                0x0003243F
  78.     (value/16.4) * i + 77  (FixMul(FixDiv(value, 0x00106666), i) + 0x004D0000)
  79.  
  80.     note: the cse optomization does not modify the expression tree in its
  81.     search for constant sub expressions as it could so hence some constant
  82.     sub expressions that could be optomized out are not.  For example, the
  83.     expression 4 + x + 5 simplifies to ((0x00040000 + x) + 0x00050000) when
  84.     if the original expression could have been rewritten to group the
  85.     constants together as in 4 + 5 + x to yeild the expression 
  86.     (0x00090000 + x).  This sort of searching could have been done
  87.     automatically, but in this version of fixit it is not.
  88.  
  89.  
  90. MATERIALS
  91.  
  92.     The Fixed point number format itself is the copyright property of
  93.     Apple computer and has been known to the public since 1983.
  94.     
  95.     The routines documented herein are the copyright property of
  96.     John Montbriand.  I am making these routines available to the
  97.     macintosh programming community because I feel it's about time
  98.     someone did!  I hope all who find them, use them well.
  99.  
  100.     Compiled and tested with MPW C, MW C, SC, and MPW PPC.
  101.  
  102.  
  103. LEGAL STUFF
  104.  
  105.     These libraries are provided for free and you may use them
  106.     in any program you make;  however, if you're particular about
  107.     having signed documentation that proves this fact in your posession
  108.     then, as I would like to ensure these libraries are widely used,
  109.     I would be glad provide such documents for you.
  110.     
  111.     I don't think this is entirly necessary, but I can understand
  112.     that some folks feel quite strongly about such issues and prefer
  113.     to do things in writing.
  114.     
  115.     If you would like for me to send you a signed document saying
  116.     that you have license to use these routines in your programs,
  117.     then send me a couple of bucks to cover postage and handling
  118.     and I'll send you back a signed letter saying you have license
  119.     to use these routines in any software you make.
  120.     
  121.     I think two or three dollars is fair as I don't really get a big
  122.     thrill out of printing stuff out and mailing it, and that's usually
  123.     enough to cover postage to anywhere in the world.  I s'pose you'd have
  124.     to figure out how much it would cost for me to mail a letter to you
  125.     from here in Canada.
  126.  
  127.  
  128. FURTHER REFERENCE
  129.  
  130.     The files fixit.h and fixit.c contain some additional fixed math routines
  131.     documented below.
  132.     
  133.     fixit.y and fixit.l contain the yacc and lex source code for the fixit MPW tool.
  134.     
  135.     Documentation regarding the fixed point data type and functions defined
  136.     inside of the toolbox for utilizing it can be found in the following
  137.     sources:
  138.     
  139.     Inside Macintosh Volume 4, by Apple Computer.  pub. Addison Wesley.
  140.        (page 63) A discussion of the new fixed point math routines introduced
  141.        along with the MacPlus.  These routines include the additional routines
  142.        defined beyond FixMul, FixRatio, and FixRound.
  143.     
  144.     Mathematical and Logical Utilities chapter of Inside Macintosh: Operating
  145.         System Utilities, by Apple Computer.  pub. Addison Wesley. (page 3-3)
  146.     
  147.     The C Programming Language 2nd edition by Brian W. Kernighan
  148.         and Dennis M. Ritchie.  Prentice Hall.
  149.     
  150.     Deviant Logic by Susan Haack.  Cambridge University Press.
  151.     
  152.     Comments for the routines provided herein have been included in the
  153.     file fixit.h.
  154.     
  155.  
  156. BE CAREFUL (CAVEATS)
  157.  
  158.     I think these routines are safe to use, but you should do your own
  159.     testing.  I have provided the source code, and if you find any bugs,
  160.     please let me know right away so I can provide corrections in future
  161.     versions.
  162.     
  163.     I advertise a finder's fee of $10.00 cash for errors in any
  164.     of my products.
  165.  
  166.  
  167. THE FIXIT TOOL
  168.  
  169.     fixit is an MPW tool that converts an expression read from standard
  170.     input into a sequence of fixed point routine calls that calculate the
  171.     same result.  The command line format for the fixit tool is as
  172.     follows:
  173.  
  174.     fixit < input > output
  175.     
  176.     fixit reads text in the format of infix mathematical expressions
  177.     from standard input writing the resuling fixmath routine calls
  178.     making up the expression to standard output.
  179.     
  180.     Here's a useful key redefinition for the tool allowing you to select
  181.     an expression in a window and automatically generate a set of fixed
  182.     point routine calls for it:
  183.     
  184.         SetKey F11  'fixit < "{Active}".§ > "{MPW}"tempxx ; ∂
  185.             catenate "{MPW}"tempxx > "{Active}".§; delete "{MPW}"tempxx'
  186.     
  187.     example:
  188.         echo "2+2" | fixit
  189.         yeilds -> 0x00040000
  190.  
  191.     note:  providing a parameter to the fixit tool forces it to
  192.     print out some help text.
  193.  
  194.  
  195. FIXIT INPUT FORMAT    
  196.  
  197.     input format for the fixit tool consists of a single infix expression.
  198.     If the expression contains any identifiers, they are assumed to be
  199.     variable names and are echoed to output in the correct position in the
  200.     expression.  The bnf for expressions follows:
  201.     
  202.     expression ::= '(' expression ')'
  203.     expression ::= expression '+' expression
  204.     expression ::= expression '-' expression
  205.     expression ::= expression '*' expression
  206.     expression ::= expression '/' expression
  207.     expression ::= expression '**' expression
  208.     expression ::= 'sin' '(' expression ')'
  209.     expression ::= 'cos' '(' expression ')'
  210.     expression ::= 'tan' '(' expression ')'
  211.     expression ::= 'sqr' '(' expression ')'
  212.     expression ::= 'sqrt' '(' expression ')'
  213.     expression ::= '-' expression
  214.     expression ::= identifier
  215.     expression ::= number
  216.     number ::= integer
  217.     number ::= integer '.' integer
  218.  
  219.     Order of evaluation is the same as the standard mathematical operations
  220.     in the following order of precidence:  parentheses, unary minus,
  221.     exponent,  multiply/divide, and then add/subtract.
  222.  
  223.     Library support for the functions sin, cos, tan, sqr, sqrt, and the
  224.     exponential operator ** is provided in the file fixit.c.  If you use
  225.     the fixit tool, you should link with a compiled version of this file.
  226.  
  227.     The fixit tool included has been compiled for the 68000 using
  228.     flex 2.4.6 and byacc 1.9 under MPW 3.4.  If you are compiling the
  229.     fixit tool with different versions of these tools you may have to
  230.     modify parts of MakeFile, fixit.y, or fixit.l.
  231.  
  232.  
  233. ROUTINES PROVIDED
  234.  
  235.     fixed point square root ( the root of x ):
  236.     
  237.         Fixed FixSqrt(Fixed x);
  238.     
  239.     
  240.     fixed point exponent function ( x to the power a ):
  241.     
  242.         Fixed FixExp(Fixed x, Fixed a);
  243.     
  244.     
  245.     fixed square (x times x):
  246.     
  247.         Fixed FixSquare(Fixed x);
  248.    
  249.    
  250.     fixed point cosine ( the cosine of x ):
  251.     
  252.         Fixed FixCos(Fixed x);
  253.  
  254.  
  255.     fixed point sine ( the sine of x ):
  256.     
  257.         Fixed FixSin(Fixed x);
  258.         
  259.         
  260.     fixed point tangent ( the tangent of x ):
  261.     
  262.         Fixed FixTan(Fixed x);
  263.  
  264.  
  265. file fixit.txt Copyright (C) 1996 by John Montbriand.  All Rights Reserved.
  266.  
  267. end of file
  268.